home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1990: Night of the Living Disc / Night of the Living Disc.hdv / Dev.CD.5 / Tools / Technical.Notes / IIGS / TN.IIGS.060 < prev    next >
Encoding:
Text File  |  1990-04-25  |  9.2 KB  |  194 lines  |  [04] ASCII Text (0x0000)

  1. Apple II
  2. Technical Notes
  3. _____________________________________________________________________________
  4.                                                   Developer Technical Support
  5.  
  6. Apple IIgs
  7. #60:    Menu Manager Memorabilia
  8.  
  9. Revised by:    Dave Lyons, Matt Deatherage, & Tim Swihart            May 1990
  10. Written by:    Dave Lyons                                           July 1989
  11.  
  12. This Technical Note discusses the Menu Manager, specifically a few anomalies 
  13. and some tips for making menus your friends.
  14. Changes since March 1990:  Corrected description of InsertMenu (you can't pass 
  15. $FFFF after all) and added a caution about the results of GetMenuTitle and 
  16. GetMItem.
  17. _____________________________________________________________________________
  18.  
  19. The Menu Manager Is Your Friend
  20.  
  21. In general, this is the truth.  You can do all kinds of nifty things with 
  22. menus, especially in System Software 5.0 and later.  However, there are a few 
  23. things you should know unless you generally are fond of pain in your life.
  24.  
  25.  
  26. Disabling Menus Gracefully
  27.  
  28. As documented, SetMenuFlag can be used to disable and enable entire menus.  
  29. When a menu is disabled, the menu title and all items within the menu are 
  30. disabled.  You may pull down a disabled menu, but you may not select any item 
  31. within it (unless the routine MenuGlobal has been used to allow inactive menu 
  32. items to be selected).
  33.  
  34. Volume 1 of the Apple IIgs Toolbox Reference says you should call DrawMenuBar 
  35. if you change the appearance of a menu title with SetMenuFlag.  You can do 
  36. this; this is fine.  It may, however, induce dizziness if used often.
  37.  
  38. A more graceful way to dim menus is to follow SetMenuFlag with HiliteMenu.  
  39. Calling HiliteMenu causes the menu title to be redrawn to reflect the current 
  40. (or new) highlighting and menu flags.  Using HiliteMenu instead of DrawMenuBar 
  41. allows you to disable and enable menus gracefully, without noticeable flicker 
  42. or threat of nasty patent infringement lawsuits from strobe light 
  43. manufacturers.
  44.  
  45.  
  46. "System" Bars Versus "Window" Bars
  47.  
  48. As far as the Menu Manager is concerned, there are only two kinds of menu 
  49. bars.  One kind is in a window and the other kind is not.  The former are 
  50. called "window" menu bars and the latter are generally referred to as "system" 
  51. menu bars.
  52.  
  53. Most people think of the System bar as the big menu bar across the top of the 
  54. screen.  This is encouraged by calls like SetSysBar, which takes a menu bar 
  55. handle and sets the menu bar across the top of the screen to that menu bar.  
  56. Trying to rename one or the other of these two concepts at this point is 
  57. probably useless; instead, this Note refers to the bar across the top of the 
  58. screen as the "System" bar (with a capital S), and menu bars not in windows as 
  59. "system" bars (with a lowercase s).
  60.  
  61. When you start the Menu Manager, it creates an empty System bar for you.  
  62. Before System Software 5.0, most people simply called NewMenu and InsertMenu 
  63. to insert menus into that System bar.  All was well in the world.
  64.  
  65. When 5.0 was released, it became very easy to create a new menu bar and all 
  66. the menus within it using the NewMenuBar2 call.  This avoids a lot of code, 
  67. and many new people use it.  The problem comes with DrawMenuBar.  If you 
  68. simply call NewMenuBar2 to obtain your menu bar and menus from resources, then 
  69. call DrawMenuBar to make them visible, you usually get an empty menu bar.  
  70. Why?  The windowPtr parameter passed to NewMenuBar2 determines whether or not 
  71. the new menu bar created is a system bar or a window bar--it does not force 
  72. the new bar to be the System (note the capital 'S') bar.  So when DrawMenuBar 
  73. draws the current System bar, it hasn't changed from the empty default one 
  74. created by MenuStartUp.
  75.  
  76. This is why Volume 3 of Apple IIgs Toolbox Reference recommends code similar 
  77. to the following:
  78.  
  79.        menuHandle := NewMenuBar2(refDesc,menuBarTRef,NIL);
  80.        SetSysBar(menuHandle);
  81.        SetMenuBar(NIL);        {NIL makes the System bar the current menu bar}
  82.  
  83. if you want your menu bar to be the one across the top of the screen.
  84.  
  85.  
  86. A Bug in NewMenuBar2
  87.  
  88. NewMenuBar2 is a handy thing to have around, but it does have a problem in 
  89. 5.0.2 and earlier.  When the Menu Manager is done with resources, it tries to 
  90. use the internal toolbox call CMReleaseResource to free them in memory.  
  91. However, it passes the wrong resource ID, and CMReleaseResource calls 
  92. SysFailMgr if it encounters any errors at all (such as Specified resource not 
  93. found).
  94.  
  95. What NewMenuBar2 does improperly is push the high word of the resource ID onto 
  96. the stack twice, instead of the high word followed by the low word.  Because 
  97. of the way the Resource Manager operates, CMReleaseResource returns with no 
  98. error if the ID passed is NIL, but the resource is not released (another good 
  99. reason not to try to use the illegal value NIL as a resource ID).
  100.  
  101. If the high word of the menu bar resource is $0000, NewMenuBar2 passes a 
  102. resource ID of NIL to CMReleaseResource, which then doesn't quite release the 
  103. resource, but returns no error.  The menu bar resource hangs around in memory 
  104. until ResourceShutDown.  It's usually fairly small, so this is no loss.  It 
  105. still takes up less room than menu strings, which had to stay in memory until 
  106. MenuShutDown.
  107.  
  108. If the high word of the menu bar resource is not zero, the bug causes 
  109. CMReleaseResource to bring down the system.  So for the time being, make sure 
  110. all menu bar resource IDs have a high word of $0000.
  111.  
  112.  
  113. Menu and Menu Title ID Numbers
  114.  
  115. Table 13-4 in Volume 1 of Apple IIgs Toolbox Reference gives a listing of menu 
  116. and menu item ID numbers.  In both lists, $0000 and $FFFF are "reserved for 
  117. internal use" and noted that $0000 usually indicates the first menu in the bar 
  118. (or first item in the menu) and $FFFF usually indicates the last menu in the 
  119. bar (or last item in the menu).  Some developers have taken this to mean that 
  120. they should give their first menu an ID of $0000 and their last one an ID of 
  121. $FFFF.
  122.  
  123. This assumption is incorrect..  The Menu Manager may change these values 
  124. internally to reflect such IDs, but they must not be assigned that way by an 
  125. application.  Some applications that use IDs of $0000 or $FFFF break under 
  126. System Software 5.0 and later.  Note that $0000 can be used as the insertAfter 
  127. parameter to InsertMenu to insert a menu at the left of a menu bar, but $FFFF 
  128. is not a valid insertAfter value.
  129.  
  130.  
  131. Desk Accessories and Menus
  132.  
  133. Some desk accessory developers would like to have their NDAs insert a menu in 
  134. the System menu bar.  While the menu itself can be inserted, the NDA cannot 
  135. detect that a user has selected an item within that menu.  The application 
  136. gets the event and does not know what to do with it.  NDAs that need a menu 
  137. can put a menu bar in their own window.  Since the mouseDown event then 
  138. happens within the NDA's window, the NDA gets the event and can handle it 
  139. normally.  Be sure to make the NDA's menu bar the current menu bar before 
  140. calling MenuSelect from within your NDA (to avoid possible conflicts between 
  141. NDA menu item IDs and application menu item IDs).  Restore the current menu 
  142. bar to the application's menu bar before returning control to the application.  
  143. Failure to do so prevents the application from finding its menus.  Apple IIgs 
  144. Technical Note #3, Window Information Bar Use documents how to put a menu in a 
  145. window's information bar.
  146.  
  147.  
  148. Documentation Error in MenuSelect
  149.  
  150. Volume 1 of Apple IIgs Toolbox Reference states that MenuSelect returns the 
  151. menu ID and the item ID of the selected item in the when field of the event 
  152. record.  This is incorrect.  MenuSelect actually returns the information in 
  153. the wmTaskData field of the task record (and this, in fact, is why you pass a 
  154. task record and not just an event record to MenuSelect).
  155.  
  156.  
  157.  
  158. Menu Strings and Bank Boundaries
  159.  
  160. NewMenu takes a pointer to a string; this string must not cross a bank 
  161. boundary.  If it does, a menu containing random garbage may result.
  162.  
  163. If your NewMenu strings are contained in your code segments, everything is 
  164. fine--code segments cannot cross bank boundaries.  Depending on your 
  165. development environment, strings that are not in a code segment may or may not 
  166. be allowed to cross bank boundaries.  If you can find no other way to 
  167. guarantee the strings do not cross a bank boundary, use NewHandle to allocate 
  168. blocks with attributes $4010 (fixed, no bank cross) and copy the strings to 
  169. these blocks.
  170.  
  171. If you create menus from resources, be sure the resources have their 
  172. noCrossBank attribute bits set.  Note that a memory block that can cross a 
  173. bank boundary usually does not, so your application may be working by 
  174. accident.
  175.  
  176. Note that this restriction applies only to menu strings, not the menu 
  177. templates that can be used with NewMenu2.
  178.  
  179.  
  180. Return Values From GetMenuTitle and GetMItem
  181.  
  182. Starting with System Software 5.0, GetMenuTitle and GetMItem can return 
  183. handles and resource IDs, not just pointers.  The type of data returned 
  184. depends on how the menu or item was created, so existing applications are not 
  185. affected.  For more information, see Apple IIgs Toolbox Reference, Volume 3, 
  186. Chapter 37, "New Features of the Menu Manager."
  187.  
  188.  
  189. Further Reference
  190. _____________________________________________________________________________
  191.   o  Apple IIgs Toolbox Reference, Volumes 1 & 3
  192.   o  Apple IIgs Technical Note #3, Window Information Bar Use
  193.  
  194.